package jers;

import java.io.Serializable;
import java.rmi.Remote;
import java.rmi.RemoteException;


/**
 * Interface para um objeto {@link Service}.
 * <p>
 * Este objeto implementa o servico a ser trabalhado.
 * Este executa o objeto {@link Job} que executa e retorna 
 * um objeto {@link Result}.
 * <br>
 * Uma instancia do objeto {@link Service} pode ser construida pela fabrica 
 * {@link Factory}.
 * <br>
 * Um {@link Service} e basicamente um objeto que implementa a 
 * interface {@link Remote} e {@link Serializable}.
 * </p>
 * 
 * @see {@link Factory}, {@link Serializable}, {@link Remote}
 * 
 * @author 
 * 		<a href="mailto:felipe.zappala@gmail.com">
 * 			Luis Felipe Zappala
 * 		</a> [ <a href="http://lncc.br/ist">ISTCC-P</a> / 2009 ]
 */
public interface Service extends Remote, Serializable {
	
	/**
	 * Executa o servico de forma sincrona e aguarda 
	 * o retorno do objeto remoto.
	 * <br>
	 * O objeto {@link Job} tem seu metodo {@link Job#run()} chamado.
	 * O objeto {@link Result} contem os resultados executados.
	 * 
	 * @see {@link Result}, {@link Job}
	 * 
	 * @param 
	 * 		job - O objeto {@link Job} a ser remotamente executado.
	 * @return 
	 * 		O objeto {@link Result} com os resultados da execucao. 
	 * @throws 
	 * 		RemoteException caso um erro ocorra.
	 */
	public Result execute(Job job) throws RemoteException;
	
	/**
	 * Despacha o servico para ser executado de forma assincrona e 
	 * nao aguarda o retorno do objeto remoto.
	 * O objeto {@link Result} com os retornos sera obtido posteriormente
	 * atraves da chamada do metodo {@link Callback#call(Result)}.
	 * <br>
	 * O objeto {@link Job} tem seu metodo {@link Job#run()} chamado.
	 * O objeto {@link Result} contem os resultados executados.
	 * O objeto {@link Callback}, implementado pelo cliente, tem seu metodo 
	 * {@link Callback#call(Result)} chamado a fim de notificar o cliente 
	 * sobre o termino da operacao.
	 * 
	 * @see {@link Result}, {@link Job}
	 * 
	 * @param 
	 * 		job - O objeto {@link Job} a ser remotamente executado.
	 * @throws 
	 * 		RemoteException caso um erro ocorra.
	 */
	public void dispatch(Job job, Callback callback) throws RemoteException;

}
